home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / ab20 / ab20_archive / datacomm / xpr / xprkermit-1.111.lzh / kermitproto.doc < prev    next >
Text File  |  1991-11-09  |  9KB  |  218 lines
  1.         The Small Portable Kermit Module (kermitproto.w)
  2.                Stephen Walton
  3.                August 2, 1988
  4.  
  5. The attached set of routines, which I have christened "kermitproto.w",
  6. represent several weeks of work.  It is intended to be a single,
  7. self-contained set of Kermit protocol routines suitable for adding to
  8. a microcomputer terminal emulation program.  As such, it does not
  9. allow the microcomputer to act as a server.  It does provide long
  10. packets, client support, and the optional protocol for a clean
  11. interrupt.
  12.     The code began its life as the routines in the book _Kermit: A File
  13. Transfer Protocol_ by Frank da Cruz (Digital Press, 1986). I have kept
  14. the original style of the book's code, only fixing bugs and adding
  15. some Lint-related items.
  16.      The code communicates to the outside world through both some
  17. subroutines which the user must provide and a set of global variables
  18. which control some aspects of the protocol.  The variables can safely
  19. be ignored for the most part;  they start out with reasonable default
  20. values which are modified as the result of Kermit transactions.  Only
  21. 3 must be set by the user interface, and my module declares these as
  22. extern so your code won't link if you don't.
  23.  
  24.             File Handling Primitives
  25.  
  26. The module contains file handling primitives written in terms of the
  27. soon-to-be ANSI standard I/O library.  These ought to work on nearly
  28. all systems, though some (MS-DOS for one) may require some changes to
  29. distinguish between text and binary files.  The ones most likely to
  30. require local changes are zltor() and zrtol() for converting file
  31. names back and forth between the local format and the generic Kermit
  32. format.
  33.  
  34.             Serial Port Primitives
  35.  
  36.      The first set of user-provided routines are for handling the
  37. serial communications.
  38.  
  39.     int ttol(char *out_string, int n)
  40.  
  41. Writes the n characters beginning at outstring to the serial port
  42. using the current settings of flow control, parity, word length, etc. 
  43. Returns the number of characters written to the port or -1 on failure.
  44.  
  45.     int ttinl(char *in_string, int max, int timeout, int eol)
  46.  
  47. Reads characters from the serial port into in_string.  It stops when
  48. either max characters have been seen or the end-of-read marker eol has
  49. been seen.  If timeout is greater than 0, then the read must be
  50. completed in no more than timeout seconds.  The value returned is the
  51. number of characters actually read or -1 on error or timeout.
  52.  
  53.     void ttflui(void)
  54.  
  55. Removes all pending readable characters from the serial port.
  56.  
  57.         Other User-Provided Routines
  58.  
  59.     int gnfile(char *filename, int length)
  60.  
  61. Copies the next file for Kermit to SEND or GET into the character
  62. string pointed to by filename, of maximum length length.  Returns a
  63. positive flag if there is a next file, 0 or negative if not.
  64.  
  65.     void sleep(int seconds)
  66.  
  67. Pause the user's program for the given number of seconds.
  68.  
  69.             Status Routines
  70.  
  71.     These routines are used to report the status of the protocol to
  72. the user's program for possible display.
  73.  
  74.     void tchar(char c)
  75.  
  76. Place the character "c" on the user's terminal.  c is a . for a
  77. successful packet transfer and a % for a retry, but c can also be
  78. anything a remote server might send in response to client commands
  79. (REMOTE COMMAND, for example).
  80.  
  81.     void tmsg(char *message)
  82.  
  83. Write the null-terminated string without a carriage return; i.e., if I
  84. call tmsg("first ") and tmsg("word"), the user should see "first word"
  85. displayed.
  86.  
  87.     void tmsgl(char *message)
  88.  
  89. Write tne null-terminated string and start a new line after
  90. displaying.
  91.  
  92.     Future update plans call for adding code to count packets, file
  93. bytes, and naks and adding a special call for displaying this type of
  94. information, similar to the screen() routine in C Kermit 4E(070).
  95.  
  96.             Starting It Up
  97.  
  98. All Kermit protocol transfers are started by doing whatever startup
  99. the user's code requires, putting the appropriate start state into the
  100. extern int start, and calling the routine proto().  Here are the supported
  101. start states and how they work:
  102.  
  103. 'v':  Receive a file.  The protocol module assumes that the remote Kermit
  104. has been given a SEND command, and passively waits (with timeouts) for the
  105. file(s) to start arriving.  Your Kermit receive subroutine could be as
  106. simple as:
  107.  
  108. void kermit_receive(void)
  109. {
  110.     extern int start;
  111.  
  112.     start = 'v';
  113.     proto();
  114. }
  115.  
  116. 's':  Send a file.  The protocol module calls gnfile() (see above)
  117. repeatedly, and sends each file requested to the remote.  The remote must
  118. have been given a RECEIVE or a SERVER command first.
  119.  
  120. 'r':  Get file(s).  The protocol module calls gnfile() for a list of files
  121. to request from a remote Kermit server.  These can generally include
  122. wildcards in the remote's syntax, for example *.FOR for all Fortran files
  123. from an MS/DOS server or *.c for all C files from a Unix server.
  124.  
  125. 'g': Kermit generic commands.  The protocol module sends the string pointed
  126. to by the extern char *cmarg to the remote as a Kermit generic server
  127. command.  The command string is of the format:
  128.  
  129.     <cmd>[%<string1>...]\0
  130.  
  131. where <cmd> is a single upper-case letter representing the Kermit generic
  132. command, and it is followed by one or more optional string arguments.  Each
  133. string is preceded by tochar() of its length.  For example, the <cmd> for a
  134. Kermit BYE (logout) command is L, and it takes no arguments, so the
  135. simplest possible BYE subroutine would be:
  136.  
  137. void kermit_bye(void) {
  138.     static char bye_command[] = "L";
  139.     extern char *cmarg;
  140.  
  141.     cmarg = &bye_command[0];
  142.     state = 'g';
  143.     proto();
  144. }
  145.  
  146. See the Kermit book for a complete list of the generic commands and the
  147. arguments required.
  148.  
  149. 'c':  Kermit REMOTE HOST command.  cmarg points to a string in the remote's
  150. command syntax which is to be executed by the remote, with output (if any)
  151. from that command being returned by the remote server.  Here is a simple
  152. example:
  153.  
  154. #define tochar(c) ((c) + 32)
  155.  
  156. void kermit_remote_host(char *remote_command)
  157. {
  158.     extern char *cmarg;
  159.     char command[90];
  160.  
  161.     state = 'c';
  162.  
  163.     cmarg = command;
  164.     cmarg[0] = tochar(strlen(remote_command));
  165.     strcpy(&cmarg[1], remote_command);
  166.     proto();
  167.     free(cmarg);
  168. }
  169.  
  170. Notice that the string pointed to by cmarg must be small enough to fit in a
  171. single Kermit packet; i.e., 90 characters or less.
  172.  
  173.             External variables
  174.  
  175. There are several which are of interest to every user program. These
  176. are, first of all, the flags parity, convert, and text.  These are
  177. simply checked against zero;  a non-zero value means that parity is in
  178. use (that is, the data path is 7 bits wide), that file names are to be
  179. converted to a generic form, and that files are to be sent or received
  180. as text, respectively.  If they are zero, they indicate an 8-bit wide
  181. data path, no file name conversion, and binary file transfer.  These
  182. are defined in kermitproto.w but must be declared in the user code;
  183. that is, the declarations "int parity", "int convert", and "int text"
  184. must appear somewhere outside of any block.
  185.     The value urpsiz must be declared by the user as well.  This is a
  186. mnemonic for "user requested packet size," and represents the size of
  187. packets the user wants to request be used.  I have written
  188. kermitproto.w so that if urpsiz is such that long packets are
  189. required, the code will also request type 3 (CRC) block checks, but
  190. the equivalent of the SET BLOCK-CHECK 3 must be issued to the remote
  191. as well.
  192.     The flags cx and cz can be used to abort a file transfer.  If cx
  193. is set upon return from ttinl(), the file currently being transferred
  194. is skipped, and any partial result from the transfer is deleted.  If
  195. cz is set, then an entire batch transfer is aborted if one is in
  196. progress.  Most Kermit programs understand the protocol used for this
  197. cancellation.  Incidentally, the reason for these flags' names is that
  198. the book recommends that Control-X be the cancel-file interrupt and
  199. that Control-Z be the cancel-batch interrupt character.
  200.     Finally, there are all of the variables which control timeouts,
  201. number of retries, block check type, and so on.  These are described
  202. in the comments at the beginning of the module.
  203.  
  204.             Compiling This
  205.  
  206. kermitproto.w is a Wart file, and should be passed through the wart
  207. preprocessor via the command:
  208.     wart kermitproto.w kermitproto.c
  209. to generate a C file to hand to your local C compiler.  wart is
  210. available (as CKWART.C) from the Kermit archives in the usual way, and
  211. is sufficiently portable so as to compile on a wide variety of systems
  212. without modification.
  213.  
  214.             Final Thoughts
  215.  
  216. 32K is longer than I thought this module would end up when I started. 
  217. I hope it does save someone some work.
  218.